<!DOCTYPE HTML PUBLIC  "-//W3C//DTD HTML 4.01 Transitional//EN"
      "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Contributing to the OpenBSD Translation Effort</title>
<link rev="made" href="mailto:www@openbsd.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="resource-type" content="document">
<meta name="description" content="Contributing to the OpenBSD Translation effort">
<meta name="keywords" content="openbsd,translation,documentation">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 2000-2008 by OpenBSD.">
</head>

<body bgcolor="#FFFFFF" text="#000000" link="#23238E">
<a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif"  border="0"></a>
<!-- Passes validator.w3.org, please keep it this way;
please, use a max of 72 chars per line -->

<!-- NOTE TO TRANSLATORS
As obvious as it may seem, this page must NOT be translated
-->

<h2><font color="#e00000">Contributing to the OpenBSD Translation
    Effort</font></h2>

<hr>

<center>
<cite>?Nec verbum verbo curabis reddere fidus interpres?</cite>
</center>

<hr>

<h3>Table Of Contents</h3>
<ul>
<li><a href="#Intro">Introduction</a>
<li><a href="#Purpose">Purpose</a>
<li><a href="#Maintenance">Maintenance</a>
<li><a href="#Joining">Joining the Translation Team</a>
<li><a href="#CVS">Using CVS</a>
<li><a href="#Guidelines">Translation Guidelines</a>
</ul>

<hr>

<h3><font color="#0000e0"><a name="Intro">Introduction</a></font></h3>

<p>
This document should contain all the information you need to
contribute to the OpenBSD translation effort as described in <a
href="translation.html">Translation of the OpenBSD documentation</a>.
Please read this document carefully and if you still have questions,
don't hesitate to contact <a href="translation.html#WHO">the translation
coordinators</a>.

<p>

<h3><font color="#0000e0"><a name="Purpose">Purpose</a></font></h3>

<p>
The purpose for translating
<a href="http://www.openbsd.org/">OpenBSD</a> web pages and other
documents is to help those who don't speak nor understand English use
OpenBSD or, if they do, they might feel more comfortable through reading
in their own language. So, by translating you are not only helping the
<a href="http://www.openbsd.org/">OpenBSD project</a> to expand, but you
are also helping people to become hooked to the system.

<p>
And of course, you'll gain good knowledge through reading and
translating at the same time.

<p>
It's important to note that besides <a
href="http://www.openbsd.org/">OpenBSD</a>, the OpenBSD project has
several websites for associated projects that you may want to translate:
<ul>
<li><a href="http://www.openssh.com/">OpenSSH</a>
<li><a href="http://www.openntpd.com/">OpenNTPD</a>
<li><a href="http://www.openbgpd.com/">OpenBGPD and OpenOSPFD</a>
<li><a href="http://www.opencvs.com/">OpenCVS</a>
</ul>

<h3><font color="#0000e0"><a name="Maintenance">Maintenance</a></font></h3>

<p>
Just translating a few web pages, or even translating the whole site
including the <a href="faq/">F.A.Q.</a>, is <strong>ABSOLUTELY
NOT</strong> enough. Actually, you could be doing more wrong than good.
<strong>Maintaining the translation up to date is just as
important</strong>. Always remember that offering outdated information
will just misguide people.

<p>
If you are not going to keep your work updated, the translation itself
will be pointless. Join us only if you think you're going to commit
yourself to your work.

<p>
<strong>Think first how much time you will be able to dedicate to the
translation. If you only have some small spare time, don't go overboard
by translating several files you won't be able to maintain
later.</strong>

<p>
Some files are easier to maintain than others, either because they are
small, or because they don't get updated too often. For instance, <a
href="plat.html">plat.html</a> is a small file, and it doesn't get
modified often. On the opposite side, <a href="plus.html">plus.html</a>
is a heavy file to translate; it grows bigger and bigger from one
release to another, and the technical and slang wording used is
very difficult to translate with accuracy.

<p>
Needless to say, some files take precedence over others. Such is the
case of <a href="index.html">index.html</a> ... or did you think
otherwise?

<h3><font color="#0000e0"><a name="Joining">Joining the Translation
    Team</a></font></h3>

<p>
Before joining the translation team, you must make sure that you have
the proper environment for translation. The required environment consists
of the following elements:
<ul>
<li>an OpenBSD box running a <strong>stable</strong> and
    <strong>maintained</strong> release
<li>OpenSSH
<li>CVS
<li>a text editor such as vi, vim, mg, etc.
<li>an HTML link checker such as linkchecker (available in the ports
    collection)
<li>an HTML validation program such as validate (available in the ports
    collection)
</ul>

<p>
Once you have the proper environment, you need commit access to the
Steelix CVS repository if you want to commit your work directly.
Otherwise, you can send them to another translator or one of the
translation coordinators to commit them for you (with due credit of
course). See <a href="translation.html#WHO">Who is doing this?</a> for
more information about the translators and translation coordinators.

<p>
The Steelix CVS repository, located at <em>steelix.kd85.com</em> is the
CVS repository used for translation. The translation work is not
committed directly to the OpenBSD CVS repository. Rather, the
translation coordinators synchronize the two repositories on a timely
basis after checking the new commits.

<p>
To commit on the Steelix CVS repository you will need an account on
<em>steelix.kd85.com</em>. To setup your account, contact one of the
<a href="translation.html#WHO">translation coordinators</a>. If he
agrees on giving you an account, you will need to give him the following
information by email:
<ul>
<li>Your full name (first name, last name). No surname/scene name is
    accepted.
<li>A permanent email address on which you can be contacted regarding
    translation work.
<li>A list of three Unix account names sorted by order of preference.
<li>Your SSH2 DSA public key as an attached file and its SHA-1
    associated hash. A minimum length of 1024 bits is required for the
    key.
</ul>

<p>
<strong><font color="#ff0000">Warning:</font></strong> you are fully
responsible for the security of your working environment and your SSH2
DSA key.

<p>
Our experience shows that some people request an account, commit some
work and then vanish without giving any good reason. Creating your
account and maintaining the account database is extra work for the
translation coordinators. So they might ask you to send the files to
another translator who will validate your work and your commitment to
the translation effort. This way, we make sure you are here to stay.

<p>
Once a translation coordinator creates your account, he will notify you
by email. The final step before starting to use the CVS repository is to
join <i>wwwcvs@docisland.org</i>, the translation mailing list. This
is a closed mailing list on which all changes made to the
Steelix CVS repository along with any translation related discussions
are posted. To join, please send an email to
<i>wwwcvs-request@docisland.org</i> with a body containing <i>subscribe</i>.

<h3><font color="#0000e0"><a name="CVS">Using CVS</a></font></h3>

<p>
Now we'll walk you through the basic CVS operations you need to perform
as a translator. If you want to have a more in-depth look into CVS
usage, please see the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&amp;sektion=1">cvs</a>
manual page and read
<a href="http://cvsbook.red-bean.com/">Open Source Development with CVS,
3rd Edition</a>, a free CVS online book by Karl Fogel and Moshe Bar.

<p>
You must have a fresh checkout (<em>CVS download</em>, also called a
<i>working copy</i> in CVS terminology) of two CVS modules on your disk.
These are:
<ul>
<li>The <i>www translation</i> CVS module. This module must be obtained
    from <i>steelix.kd85.com</i>, the OpenBSD translation CVS server.
    This is the module on which all translation work happens.
<li>The <i>www</i> CVS module. This module must be obtained from one of
    the many <a href="anoncvs.html"> anonymous OpenBSD CVS mirrors</a>
    out there. This will be your source for the original English files
    that you need to translate.
</ul>

<p>
<strong><font color="#ff0000">Note:</font></strong> while the <i>www
translation</i> CVS module holds also the English files, they must not
be used since they are rarely kept in sync with the English files found
on the anonymous OpenBSD CVS mirrors.

<p>
The checkouts and later operations are performed using SSH for
transport, as you might have guessed after reading the <a
href="#Joining">Joining the Translation Team</a> section.

<p>
Let's see how the checkouts are performed.

<h4>Initial checkout of the 'www translation' CVS module</h4>
We will assume that you are going to put all the translation work files
and directories under <i>/home/username/devel/openbsd/</i>. Of course,
this is absolutely not a requirement. This scheme is solely used for the
examples below. Change as needed.

<p>
Issue the following commands to checkout the <i>www translation</i> CVS
module from <i>steelix.kd85.com</i>:

<pre>
  $ cd /home/username/devel/openbsd/
  $ cvs -d "username@steelix.kd85.com:/cvs" checkout -d "steelix-www" www
</pre>

<p>
The latter command will connect to <i>steelix.kd85.com</i> using SSH as
user <i>username</i> to retrieve a working copy of the <i>www
translation</i> CVS module and store it under <i>steelix-www</i>.

<p>
The SSH authentication is set up to use your SSH2 key, which requires
you to enter your passphrase to proceed. SSH is used for checkout and
all other CVS operations. By default, this will ask you everytime for
your passphrase. To save some typing, you might want to load your SSH2
private key in
<i><a 
href="http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-agent&amp;apropos=0&amp;sektion=0&amp;manpath=OpenBSD+Current&amp;arch=i386&amp;format=html">ssh-agent</a></i> using <i>keychain</i> (available in the ports collection) or some
home-cooked recipe.

<p>
After successfully entering your passphrase, CVS will proceed with
checking out your working copy. Depending on your connection speed, this
operation may take some time to complete.

<p>
Once the checkout terminates, you will have a <strong>working copy of
the www translation CVS module</strong>.

<h4>Initial checkout of the 'www' CVS module</h4>
To obtain a working copy of the <i>www</i> CVS module, you need to find
an OpenBSD anonymous CVS mirror near you that is updated frequently.
Suppose you are located in Germany. According to the <a
href="anoncvs.html">OpenBSD AnonCVS</a> page,
<i>anoncvs.de.openbsd.org</i> looks like a good candidate. It is
maintained by one of the OpenBSD developers (Alexander von Gernler) and
updated every 2 hours. Moreover, it offers CVS through SSH. Let's use it
to obtain the working copy of the <i>www</i> CVS module:

<pre>
  $ cd /home/username/devel/openbsd
  $ cvs -d "anoncvs@anoncvs.de.openbsd.org:/cvs" checkout -d "openbsd-www" www
</pre>

<p>
The latter command will connect to
<i>anoncvs@anoncvs.de.openbsd.org</i> using SSH as user <i>anoncvs</i>
to retrieve a working copy of the <i>www </i> CVS module and store it
under <i>openbsd-www</i>. SSH won't ask for authentication since we are
using an anonymous CVS account. Depending on your connection speed, this
operation may take some time to complete.

<p>
Once the checkout terminates, you will have a <strong>working copy of
the www CVS module</strong>.

<h4>Organization of the 'www' CVS module</h4>
<a name="sections"></a>
The <i>www</i> CVS module that the OpenBSD and associated projects'
websites are made of is constituted of ten sections.
The table below lists all these sections and what they represent.

<p>
<table border="1">
<tr valign="top"><td>
<strong>[base]</strong>
</td><td>
<a href="http://www.openbsd.org/">http://www.openbsd.org/</a> and
everything under it <strong>except</strong> for the FAQ available at 
<a href="faq/">http://www.openbsd.org/faq/</a>.
</td></tr><tr valign="top"><td>
<strong>[faq]</strong>
</td><td>
<a href="faq/">http://www.openbsd.org/faq/</a> 
and everything under it <strong>except</strong> for the PF User Guide
available at 
<a href="faq/pf/">http://www.openbsd.org/faq/pf/</a>.
</td></tr><tr valign="top"><td>
<strong>[openbgpd]</strong>
</td><td>
<a href="http://www.openbgpd.org/">http://www.openbgpd.org/</a> 
and the associated subdirectories.
</td></tr><tr valign="top"><td>
<strong>[opencvs]</strong>
</td><td>
<a href="http://www.opencvs.org/">http://www.opencvs.org/</a>
and the associated subdirectories.
</td></tr><tr valign="top"><td>
<strong>[openntpd]</strong>
</td><td>
<a href="http://www.openntpd.org/">http://www.openntpd.org/</a> 
and the associated subdirectories.
</td></tr><tr valign="top"><td>
<strong>[openssh]</strong>
</td><td>
<a href="http://www.openssh.com/">http://www.openssh.com/</a> 
and the associated subdirectories <strong>except</strong> the usage
subdirectory.
</td></tr><tr valign="top"><td nowrap="nowrap">
<strong>[openssh-usage]</strong>
</td><td>
<a href="http://www.openssh.com/usage/">http://www.openssh.com/usage/</a>.
</td></tr><tr valign="top"><td>
<strong>[papers]</strong>
</td><td>
<a href="papers/">http://www.openbsd.org/papers/</a> and the associated
subdirectories.
</td></tr><tr valign="top"><td>
<strong>[pf]</strong>
</td><td>
<a href="faq/pf/">http://www.openbsd.org/faq/pf/</a> and everything
under it.
</td></tr><tr valign="top"><td>
<strong>[porting]</strong>
</td><td>
<a href="porting/">http://www.openbsd.org/porting/</a> and the
associated subdirectories.
</td></tr>
</table>

<p>
Translated pages in a given language for a given section are located
under a subdirectory in that section. The subdirectory name is the
two-letter
<a href="http://lcweb.loc.gov/standards/iso639-2/englangn.html">ISO 639-1 language code</a> 
of the language. For example, french [faq] pages are located under
<a href="faq/fr/">http://www.openbsd.org/faq/fr/</a>.

<p>
The <i>www translation</i> CVS module is organized in an identical
fashion. While the <i>www</i> CVS module is your source for the English
original files that you need to translate or sync against, the <i>www
translation</i> CVS module will host all your translation work as we
mentioned earlier.

<h4>Working on the 'www translation' module</h4>
You <strong>must not</strong> touch any file within the first level of
any <a href="#sections">section</a> of the <i>www translation</i> CVS
module. If, by mistake, you edited and modified one of the files in the
first level, don't edit it back to reverse those changes, the timestamps
will have changed and you will mess the remote repository next time you
<kbd>'cvs up -PAd'</kbd> followed by <kbd>'cvs commit'</kbd>. Instead,
just <kbd>rm -f</kbd> that file and follow the instructions to <a
href="#update">update</a>. An update from the CVS repository will
restore that file in your working copy. Likewise, avoid changing the
files from languages other than yours.

<p>
You must do your work within your language directory.  If it doesn't
exist yet, you can read how to <a href="#add">add</a> a new directory
or file in the next section.

<p>
Thus, for a given language such as Spanish, the language directory will
be denoted by the two-letter
<a href="http://lcweb.loc.gov/standards/iso639-2/englangn.html">ISO
639-1 language code</a>, <i>es/</i> in this case, and files will be
organized as follows:
<ul>
<li><em>steelix-www/es/</em> - www.openbsd.org/es/ files.
<li><em>steelix-www/faq/es/</em> - www.openbsd.org/faq/es/ files.
<li><em>steelix-www/openssh/es/</em> - www.openssh.com/es/ files.
<li>...
</ul>

<p>
This is important to remember as far as relative <a
href="#Links">links</a> go.

<a name="add"></a>
<h4>Adding directories and files</h4>
Suppose that there was no Spanish directory as yet under the
<strong>[pf]</strong> section. We would create it first on our local
repository:

<pre>
  $ cd ~/devel/openbsd/steelix-www/faq/pf
  $ mkdir es
</pre>

and then we would have to <strong>add</strong> it to the CVS repository:

<pre>
  $ cvs add es
</pre>

<p>
That was easy. Next we would copy an English original file that we would
like to translate from the <i>www</i> module (e.g.
<i>openbsd-www/faq/pf/index.html</i>) into the es/ directory and would
add it as well:

<pre>
  $ cd  ~/devel/openbsd
  $ cp -p openbsd-www/faq/pf/index.html steelix-www/faq/pf/es/
  $ cd steelix-www/faq/pf/es
  $ cvs add index.html
</pre>

<p>
<strong>Note<sup>(1)</sup></strong>: while <kbd>cvs add</kbd>'ing a
directory will change the remote repository straight away, it won't do
so if we were adding a file until we run the <a
href="#commit">commit</a> command.

<p>
<strong>Note<sup>(2)</sup></strong>: see the <kbd>rm</kbd> command in the
CVS manual page to know how to remove a file or directory.

<a name="update"></a>
<h4>Updating files</h4>
If, while in the <em>steelix-www/</em> directory, we ran the command and
options:

<pre>
  $ cd  ~/devel/openbsd/steelix-www
  $ cvs up -PAd
</pre>

the effect would be twofold:

<ul>
<li>All changes made by others to the <i>www translation</i> module on
    the CVS repository would be automatically applied to our working
    copy. The working copy <strong>will</strong> change.
<li>All changes made by us to our working copy <em>would be ready to be
    "uploaded"</em> to the CVS repository. The <i>www translation</i>
    module on the CVS repository <strong>will not</strong> change until
    we run the <a href="#commit">commit</a> command.
</ul>

<p>
<strong>Note:</strong> it is suggested to run this command before we
start making changes to our working copy, so we can see what changes
have been made by others and avoid conflicts.

<a name="commit"></a>
<h4>Committing changes</h4>
This is the mother of all commands:

<pre>
  $ cd faq/pf/es
  $ cvs commit
</pre>

<p>
This command will load an editor such as <i>vi</i> so you can enter a
commit message. This message will allow others to have an idea of the
change(s) that you've made. It is automatically posted to the
translation mailing list.

<p>
Needless to say that you only commit when you feel your changes should
definitely go into the <i>www translation</i> of the CVS repository.

<a name="revert"></a>
<h4>Reverting a change</h4>
If you have committed a file and you discover that your commit breaks
something, you have to revert the commit as soon as possible. Assume the
problem lays in a file called <i>somefile</i>. Follow the procedure
below to revert it to an unbroken revision:

<pre>
   $ cvs log somefile
</pre>

<p>
At the top of the output, you can see the latest revision of the file
(your latest modifications). For example, <i>1.192</i>. You have to
checkout the previous revision and commit it to fix the issue.

<pre>
   $ cvs update -A somefile
   $ rm somefile
   $ cvs update -p -r1.191 somefile > somefile
</pre>

<p>
<i>1.191</i> is indeed the previous revision. It is now in your working
copy. You should commit it to restore the file to a working state:

<pre>
   $ cvs commit -m "restoring previous version" somefile
</pre>

<a name="wrongdir"></a>
<h4>Committing in a bad directory</h4>
If you have committed a file in a bad directory, you have to fix things
by moving it to the right directory as soon as possible. Assume you have
committed <i>somefile</i> to <i>baddir</i> while it should really go
into <i>gooddir</i>. Here is the procedure to correct your mistake:

<pre>
   $ pwd
   ...devel/openbsd/steelix-www/.../baddir
   $ cvs remove somefile
   $ mv somefile path/to/gooddir
   $ cd path/to/gooddir
   $ pwd
   ...devel/openbsd/steelix-www/.../gooddir
   $ cvs add somefile
   $ cvs commit -m "move file to the right location" somefile
</pre>

<h3><font color="#0000e0"><a name="Guidelines">Translation
    Guidelines</a></font></h3>

<p>
The following is a set of general translation guidelines that will help you
get your job as a translator done correctly.

<h4>Stick to translating the pages!</h4>
<strong>Although we really welcome any help to make the webpages better,
your job as a translator is _NOT_ to enhance the pages with pictures,
tags, email addresses or anything else that hasn't been in the page
before!</strong>

<p>
If you do have suggestions concerning the content of a page, send them
to <a href="mailto:www@openbsd.org">www@openbsd.org</a>. If they are
good, they can be included by one of the developers.

<h4>Translation Tags</h4>
If you have freshly translated a page to your language you would like to
see it committed. And it should and will be maintained. To make this
easier and let everybody see who committed this page and follow changes
using CVS we use some special tags at the end of the page.

<p>
We simply enhance the original &#036;OpenBSD&#036; tag with two more
lines, in which we document from which version our translated file comes
from and which version of the translation it is.

<p>
A typical OpenBSD ID tag looks like this:

<pre>&lt;small&gt;
&#036;OpenBSD: index.html,v1.330 2001/04/24 07:11:44 jufi Exp &#036;
&lt;small&gt;
</pre>

From this, you must change the opening and closing <tt>$</tt>'s and
change them to an opening ``<tt>Originally [</tt>'' and closing
``<tt>]</tt>'', and add a <tt>&#036;Translation&#036;</tt> and an
<tt>&#036;OpenBSD&#036;</tt> ID tags. Since the <tt>Originally</tt> and
<tt>&#036;Translation&#036;</tt> tags are used by translators only, you
must comment them so they don't appear when the pages are displayed on a
browser:

<pre>&lt;small&gt;
&lt;!--
Originally [OpenBSD: index.html,v 1.330 ]&lt;br&gt;
&#036;Translation&#036;&lt;br&gt;
--&gt;
&#036;OpenBSD&#036;
&lt;/small&gt;
</pre>

Notice that we've also added the <tt>&lt;br&gt;</tt> tags here, which
are needed to have each ID tag on a separate line of its own. And we've
also stripped off part of the original OpenBSD ID tag, as that bit is
not really needed.

<p>
As for the <tt>&#036;Translation&#036;</tt> and
<tt>&#036;OpenBSD&#036;</tt> tags, the Steelix and OpenBSD CVS servers
will take care of each respectively. So, next time you modify that file,
all you will have to do is to replace the content within the
<tt>Originally [blah... ]</tt> ID tag again.

<p>
But you should check from file to file whether everything is correct
and compare to other files, your own or even those from other languages.

<p>
<strong><font color="#ff0000">Note:</font></strong> the amount and
positions of spaces and words in the tags are absolutely precise and not
to be changed!
Otherwise you will find your file not recognized correctly by the
scripts which build the
<!--
<a href="http://steelix.kd85.com/translation/status.html">status page</a>!
-->
<a href="http://www.altroot.org/openbsd/steelix-report/status.html">status page</a>!

<p>
It is really helpful to have a look at the pages of the other
translators, and watch how they did it.

<h4>Meta tags</h4>
Meta tags must not be translated or modified, save for the
<strong>title</strong> tag which must be translated of course.
 
<a name="Links"></a>
<h4>Links</h4>
When translating a file from the original English html file to another
language, we also need to change the relative links to have them point
to the right file they reference.

<p>
As a first example, let's suppose you are translating the
<i>index.html</i> file, and you find a link to the orders.html file like
this:<br> <tt><strong>&lt;a href="orders.html"&gt;orders.html&lt;/a&gt;</strong></tt>.

<p>
This means that it will link <em>index.html</em> to
<em>orders.html</em> <strong>if they are in the same directory
level!</strong>.  So, if you dont have an <em>orders.html</em> file
translated yet in your language directory, it will point to a non-
existent file. Just go one directory back to link it to the file in the
English directory for this example case:<br> <tt><strong>&lt;a
href="../orders.html"&gt;orders.html&lt;/a&gt;</strong></tt>.

<p>
When you have the <em>orders.html</em> file translated and already in
your language directory, you can then strip the
<tt><strong>../</strong></tt> off and let it point to the file in your
directory.

<p>
For a file in the <em>faq/</em> directory, this is a bit different,
since your language directory will be something like <em>faq/de/</em>.
So, if you were translating <em>faq1.html</em> and found a link to the
<em>faq2.html</em> like this:<br>
<tt><strong>&lt;a href="faq2.html"&gt;faq2.html&lt;/a&gt;</strong></tt>

<p>
you would have to go back one level as in the previous example to link
to the English file (or none if you already have faq2.html translated in
your language directory).<br> BUT, if you had to link from your faq
language directory to a file, say, in the first level directory (e.g.
<em>orders.html</em>), you would have to go back <strong>2
levels</strong>:<br> <tt><strong>&lt;a
href="../../orders.html"&gt;orders.html&lt;/a&gt;</strong></tt>.

<p>
AND, if <em>orders.html</em> were a translated file, then you would have
to go back two levels and then one level forward to your language
directory:<br> <tt><strong>&lt;a
href="../../de/orders.html"&gt;orders.html&lt;/a&gt;</strong></tt>.

<p>
We know this looks messy, but you will get used to it and the best you
can do to avoid errors is to check links before you commit (and as you
are at it, also check the id tags).

<p>
One final note on links: links must *always* be relative, except for
external links and links from www.OpenBSD.org to www.OpenSSH.com and
vice versa.

<h4>Links to images</h4>
You'll find most images inside the <em>images/</em> directory.  In fact,
all images are kept in there, except for <em>back.gif</em>, which is
<em>openbsd-www/back.gif</em>.

<p>
This means that when a file is translated and goes into its language
directory, the links to the images <i>must</i> be changed too. So, the
most commonly used image on the website looks like this on any original
file:

<pre>&lt;a href="index.html"&gt;&lt;img height="24" width="24" src=<strong>"back.gif"</strong> alt="OpenBSD"&gt;&lt;/a&gt;
</pre>

<p>
but since the translated file will be placed in a different directory,
you will have to change the link to <em>back.gif</em> to get it right:

<pre>&lt;a href="index.html"&gt;&lt;img height="24" width="24" src=<strong>"../back.gif"</strong> alt="OpenBSD"&gt;&lt;/a&gt;
</pre>

<p>
For the remaining cases, where images are kept in the <em>images/</em>
directory:

<pre>&lt;a href="art1.html"&gt;&lt;img border="0" src=<strong>"images/openbsd-logo.gif"</strong> height="195"
width="520" alt="[OpenBSD 3.7]"&gt;&lt;/a&gt;
</pre>

<p>
should be changed to:

<pre>&lt;a href="art1.html"&gt;&lt;img border="0" src=<strong>"../images/openbsd-logo.gif"</strong> height="195"
width="520" alt="[OpenBSD 3.7]"&gt;&lt;/a&gt;
</pre>

<p>
This is easy when dealing with normal web pages, but if the file is in
the <em>faq</em> or <em>openssh</em> directories, then you have to use
something like:

<pre>&lt;a href="art1.html"&gt;&lt;img border="0" src=<strong>"../../images/openbsd-logo.gif"</strong> height="195"
width="520" alt="[OpenBSD 3.7]"&gt;&lt;/a&gt;
</pre>

<h4>Accentuated letters</h4>
Since some languages such as French make extensive use of accentuated
letters, a translator must make sure that the accents on the letters are
put in the right places and in the right styles (&egrave; not &eacute;
in a word such as &quot;probl&egrave;me&quot;). The HTML code must not
contain the accentuated letters in HTML codification format (such as
&quot;&amp;eacute;&quot; for &quot;&eacute;&quot;).

<h4>Punctuation</h4>
There are also differences in punctuation between English and other
languages, and you need to respect them. Take French for example. The
&quot;!&quot;, &quot;?&quot;, &quot;:&quot; signs always take a space
before and a space after as in &quot;Le fran&ccedil;ais est une
sacr&eacute;e langue ! n'est-ce pas ?&quot;.

<h4>Line wrapping</h4>
Verify that your HTML editor wraps lines correctly at 80 columns. If your
editor can't do that, there are other ways to do this such as using the
Text::Autoformat Perl module. We won't be accepting uncorrectly wrapped
files anymore since it requires non-wanted extra work from the
coordinators.

<h4>English words</h4>
English words that cannot be easily translated or that should be kept
as-is for clarity must be double-quoted.

<h4>Quotes</h4>
Quotes from users, developers, and other people must not be translated.
Translating them, without changing meaning, is extremely difficult.

<h4>Spell checking</h4>
It is highly recommended to use a spell checker in order to validate
your work.

<h4>Link checking</h4>
It is highly recommended to use a link checker such as the
<a href="http://linkchecker.sourceforge.net/">linkchecker</a> program
(available in the ports collection) to verify the links in the
translated files.

<h4>Mistakes and typos in the original versions</h4> 
As in any translation work, you may notice mistakes and/or typos in the
original English version of the file that you are currently translating.
Please report them back to <a
href="mailto:www@openbsd.org">www@openbsd.org</a>, so they can be fixed
by one of the developers. It really helps the project to keep up with
the quality standards it strives to maintain.

<h4>Translation status</h4>
The
<a href="http://steelix.kd85.com/translation/status.html">OpenBSD
Translation Status</a>
status. It is generated hourly using <i>makereport</i>, a Perl script
that you can find in the <i>trtools</i> module on the Steelix CVS
repository. You can run <i>makereport</i> by yourself if you want to
have more frequent status updates or want to generate a status page only
for your language.

<h4>HTML tag differences report</h4>
The <a href="http://steelix.kd85.com/translation/tagreport/"
>OpenBSD Translation Tag Report</a> page helps translators keep their
pages correct with respect to the original versions. It reports any
differences found in HTML tags, except allowed differences such as
hyperlinks as explained above.
The report page contains more instructions on how you can use this tool.
A complete tag differences report is generated daily using <i>tagdiff</i>,
a Perl script that you can find in the <i>trtools</i> module on the
Steelix CVS repository. You can run <i>tagdiff</i> by yourself if you
want to have more frequent updates or want to generate a tag report only
for your language.
Please try to keep the percentage of problem pages as low as possible!

<p>

<hr>
<a href="index.html"><img height="24" width="24" src="back.gif"
border="0" alt="OpenBSD"></a> 
<a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br>
<small>
$OpenBSD: translation-explained.html,v 1.20 2008/02/23 12:49:22 saad Exp $
</small>

</body>
</html>
